Process Platform allows different methods of user authentication of which one is WS-Security SAML Token Profile. This allows an external application or components to send a soap request with a SAML 2 assertion in the WS-Security SOAP header. The Process Platform identity framework will use the user identity available in the SAML assertion and use that to resolve the actual Process Platform user. Typically a SAML assertion is digitally signed. This allows the receiver to validate the origin of the SAML assertion. To validate the SAML assertion a trust relation has to be configured between the sender and receiver. Once this trust relation is configured, the  Process Platform can validate the digital signature of the SAML assertion. The SAML assertion also contains additional conditions, like an audience restriction and in what time-frame the SAML assertion is valid. See Example of SAML Assertions for a practical example of the use of SAML assertion.

Managing Trust

To trust external SAML assertions provided in the Process Platform, you must do the following:

1. Add the certificate that is used to sign the SAML assertion to the SAML Trust store. 
   The actual certificate that is used to sign the SAML assertion must be added to the SAML Trust store. Note that certificates present in the SAML Trust store only will be used for the validation of SAML assertion. 
2. Add the complete certificate chain of the signing certificate to the generic Trust store. All certificates in the chain of the signing certificate must be available in the generic trust store.

Both the signing certificate and the certificates in the certificate chain can be added at shared or organization level, depending upon the need. Certificates added to shared level trust store can be used for the validation of SAML assertions of all organizations. Certificates at the organization level of the trust store can only be used within that organization.

Removing the certificate from the SAML Trust store also invalidates the trust relation with the SAML assertion provider. Adding a certificate to the trust does not require a Service Container restart; the settings are hot, that is, they can be picked up automatically.

Adding certificates to the generic and SAML trust store can be done through the Security Administration application.

Do the following to add a certificate for a SAML Trust relation:

1. On CUSP > My Applications, click  (Security Administration).
2. The Security Administration window appears and select the SAML Trust tab. This tab contains a table showing all trusted certificates specifically for trusting incoming SAML 2 assertions through WS-Security in the SOAP header.
3. Click . The Load New Certificate window appears.
4. Upload or paste the relevant certificate.
5. Optionally, you can change the alias under which the certificate is stored.
6. Click OK to import the certificate.

A certificate is added. Note that it is not needed to restart any Service Container, the trusted certificate is picked up automatically.

Adding certificates from the certificate chain can also be done in the Security Administration as described in Adding a New Certificate.

Audience restriction

SAML assertions can contain conditions. One of these conditions is the audience restriction. This condition is there so that the receiver can confirm the SAML assertion provided is actually meant for this receiver.

The default value expected for a Process Platform instance is the its instance name or the value of the wcp property cordys.instance.name.

It is possible to configure the expected audience restriction value. This can be done by setting the property cordys.inboundsaml2.audiencerestriction.template in wcp.properties to the desired value or pattern. In the pattern the following properties can be used:

The default value of the property is $INSTANCE.

The following are the samples of the audience restriction property values:

cordys.inboundsaml2.audiencerestriction.template=testSP
cordys.inboundsaml2.audiencerestriction.template=$INSTANCE
cordys.inboundsaml2.audiencerestriction.template=test$INSTANCE
cordys.inboundsaml2.audiencerestriction.template=$ORGANIZATION_$INSTANCE

If the property value is empty, the Audience restriction check will not be performed.

The following is a sample SAML assertion condition: 

    <saml2:Conditions NotBefore="2014-02-04T14:26:30Z" NotOnOrAfter="2014-02-04T14:46:30Z">
        <saml2:AudienceRestriction>
            <saml2:Audience>defaultInst</saml2:Audience>
        </saml2:AudienceRestriction>
    </saml2:Conditions>